/**
 * <h3>ThemeService</h3>
 * <p> 大赛管理服务接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义大赛模块的核心业务逻辑接口，包括主题大赛的增删改查、作品管理、排名计算等 </p>
 * <p> 支持主题大赛的创建、修改、删除、查询，以及作品统计和自动排名等核心业务逻辑 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *     <li> 作者：郭强 </li>
 *     <li> 创建日期：2025年05月18日 14:20:15 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *     <li> 参考实现：{@link ThemeServiceImpl} </li>
 *     <li> 示例代码：{@code List<ThemeDTO> themes = themeService.selectThemeList(dto);} </li>
 * </ul>
 *
 * @apiNote 接口应保持职责单一原则，避免将多个不相关功能合并定义
 * @implSpec 继承自 {@link IService<ThemeDTO>}，复用MyBatis Plus提供的通用接口
 * @since v1.0.0.0
 */
package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.dto.ThemeDTO;
import com.dnndo.system.domain.dto.ThemeInfoDTO;
import com.dnndo.system.domain.dto.ThemeQueryDTO;
import com.dnndo.system.domain.dto.WorkDTO;
import com.dnndo.system.domain.vo.ThemeInfoVO;
import com.dnndo.system.domain.vo.ThemeQueryVO;

import java.util.List;

/**
 * 大赛管理服务接口
 * 
 * @see com.dnndo.system.domain.dto.ThemeDTO
 * @see com.dnndo.system.service.impl.ThemeServiceImpl
 */
public interface ThemeService extends IService<ThemeDTO> {

    /**
     * 根据条件查询大赛列表（分页）
     *
     * @param dto 查询条件封装对象
     * @return List<ThemeDTO> 符合条件的大赛信息列表
     * @see com.dnndo.system.domain.dto.ThemeDTO
     */
    List<ThemeDTO> selectThemeList(ThemeDTO dto);

    /**
     * 根据ID获取大赛详细信息
     *
     * @param themeId 大赛唯一标识符
     * @return ThemeDTO 包含详细信息的对象
     * @see com.dnndo.system.domain.dto.ThemeDTO
     */
    ThemeDTO selectThemeById(Long themeId);

    /**
     * 新增大赛信息
     *
     * @param dto 封装新增数据的DTO对象
     * @return int 受影响的记录数
     * @see com.dnndo.system.domain.dto.ThemeDTO
     */
    int insertTheme(ThemeDTO dto);

    /**
     * 修改大赛信息
     *
     * @param dto 封装更新数据的DTO对象
     * @return int 受影响的记录数
     * @see com.dnndo.system.domain.dto.ThemeDTO
     */
    int updateThemeById(ThemeDTO dto);

    /**
     * 删除指定ID的大赛信息
     *
     * @param themeId 要删除的大赛ID
     * @return int 受影响的记录数
     * @see com.dnndo.system.domain.dto.ThemeDTO
     */
    int deleteThemeById(Integer themeId);

    /**
     * 新增主题大赛查询方法
     *
     * @param params 主题大赛查询参数
     * @return List<ThemeInfoVO> 主题大赛信息列表
     * @see com.dnndo.system.domain.dto.ThemeInfoDTO
     * @see com.dnndo.system.domain.vo.ThemeInfoVO
     */
    List<ThemeInfoVO> competition(ThemeInfoDTO params);

    /**
     * 主题大赛详情根据id查询
     *
     * @param dto 主题大赛查询条件
     * @return ThemeQueryVO 主题大赛详细信息
     * @see com.dnndo.system.domain.dto.ThemeQueryDTO
     * @see com.dnndo.system.domain.vo.ThemeQueryVO
     */
    ThemeQueryVO theme(ThemeQueryDTO dto);

    /**
     * 查询当前主题大赛的所有作品
     *
     * @param params 作品查询参数
     * @return List<WorkDTO> 作品列表
     * @see com.dnndo.system.domain.dto.WorkDTO
     */
    List<WorkDTO> work(WorkDTO params);

    /**
     * 查询所有主题大赛总数
     *
     * @param params 查询条件
     * @return int 主题大赛总数
     * @see com.dnndo.system.domain.dto.ThemeInfoDTO
     */
    int countCompetition(ThemeInfoDTO params);

    /**
     * 获取当前主题大赛写的所有作品总数
     *
     * @param dto 查询条件
     * @return int 作品总数
     * @see com.dnndo.system.domain.dto.WorkDTO
     */
    int countTheme(WorkDTO dto);

    /**
     * 查询所有已结束且排名状态为0（未计算）的主题ID
     *
     * @return List<Integer> 包含符合条件的主题ID的列表
     * @see com.dnndo.system.domain.Theme
     */
    List<Integer> selectExpiredAndUnrankedThemes();

    /**
     * 更新主题的排名状态为1（已计算）
     *
     * @param themeId 要更新状态的主题ID
     * @return int 受影响的行数，成功则为1
     * @see com.dnndo.system.domain.Theme
     */
    int updateThemeRanked(Integer themeId);
}
